BBS in a Box 15/BBS in a box XV-1.iso/Files/Util/B/Bind Icons.sit/Bind.Icons.Manual

Text File | 1987-05-12 | 9.4 KB | 183 lines | [TEXT/MSWD]

                          ICON BINDING UTILITY
                                        -- John Jeppson


   This program is the EASIEST way to bind a new icon to an application.
The program will actually make the Finder display a new icon for your
completed application.  What's more it will really work..  provided you
take one simple precaution to avoid sabotaging yourself.  It should work,
in fact, for any application: MacForth turnkeys, stand-alone "C"
applications, assembled applications you have written yourself, or
applications you have bought, begged, or whatever.

   The program will do more than that.  It will also create or re-create
all those nasty BNDL's and FREF's that your application is supposed to
have.  It will operate on the "Desk Top" file to excise its old habits.
And finally it will merge a bag of resources, if you have any, that your
new application will require.


The Contest: Man vs. Machine.

   Let's face it.  This is mortal combat, you against Finder, your ulcers
against his monumental stubbornness.  All you want is a little recognition
for your hard work, your own icon proudly displayed on the desktop.  All
Finder wants is to get away with as little work as possible.

   So maybe you thought you would try the "death thrust", stabbing Finder
in the back by deleting "Desk Top" from the disk.  But if you don't
understand the game then Finder may rise up from the ashes with the same
old icon, and laugh you right into your grave.


How To Make It Go:

1.  The program begins by asking you to locate the target application with
the standard file dialog.  The target can be in any folder on any volume.

2.  Next you see the main dialog in which you enter the following
information:


    APPLICATION SIGNATURE: This is a FileType, 4 bytes of ascii text.
Should be all uppercase printing characters, and should not conflict with
standard filetypes such as TEXT, DATA, etc.  Don't confuse this with the
application's filetype which is always APPL.  The signature is a different
filetype.  If your application makes or uses "daughter" files then those
files will refer to their parent's signature as the "creator".  It's the
same thing.  Application signature = creator = a filetype.  You need one
whether your application makes daughter files or not.  You should try to
make it unique.

   "Phooey!", you say, "I've got this application, and I want to stick a
new icon on it, and I couldn't care less what signature the damn thing
has".  This is a mistake.  The "glue" that sticks a particular icon to your
application is a resource called a BNDL ("bundle"), and various BNDL's are
distinguished from each other by their signatures-- sort of like names.  If
you want a different icon to be displayed then you will be changing the
contents of the BNDL, but Finder simply cannot cope with two "different"
BNDL's which have the same signature.  He simply won't try, and you'll be
up the creek.  If you want a new icon, then use a new signature.  This
problem is discussed at greater length below.

    It's easy to make a new signature; just type four capital letters in
the little box.

   ICN#ID: This is the resource number of your new icon.  We aren't going
to draw the icon for you, you'll have to do that yourself, probably with
Resource Editor.  You should already have done this, and assigned the icon
(ICN# really, a pair of icons) an ID number between 128 and 32767
inclusive.  It doesn't much matter which, as long as the number is unique
(among ICN# ID's) within your own application.  You should store the
completed ICN# resource in your application, or in a special bag file we
will tell you about in a moment (NOT MacForth's "Resource Bag", if you are
making a MacForth turnkey).

   VERSION STRING: This is strictly optional; you can leave it blank.
Traditionally this is an ascii string containing the version number or
date.  For example: "RingLocator version 1.02, copyright 1986, Frodo".

   (other) FILETYPEs: These, if any, are the FileTypes and associated ICN#
ID numbers of daughter filetypes which your application may create.  For
example, MacForth may create BLKS files and these will be displayed with
their own icon.  Similarly, MacWrite creates WORD files which also have a
distinctive icon.  These ICN# resources, if any, should be prepared and
stored along with the parent application's ICN# resource, wherever you put
that.

3. When you have done all this click "OK"; the program will do the rest.
It will:
    (a) Merge your resources (deleting old versions) - see below;
    (b) Remove target's old signature, BNDL and FREF's, if any;
    (c) Build new signature, BNDL, and FREF's as necessary;
    (d) Weed out the Desk Top of old bad stuff.

Illuminating progress messages will appear.  Finally you will be directed
to return to the Finder to view your new icon.

   In addition to operating on your application, the program also saves
your dialog entries in a disk file.  If you are unhappy with the final
result you can modify your application or turnkey and run "Bind.Icons"
again.  This time the dialog will come up with your old entries in place,
so you will probably just need to click "OK".

   The "Revert" button returns the dialog entries to the configuration last
stored (by pressing "OK") or to blanks if this is the first time around.

4.  The data file which saves the dialog info has a special name.  It is
the same as your target application's name with the suffix ".bag".  For
example, if your application's name is "SuperScooper" then the data file
will be named "SuperScooper.bag".  For long-winded programmers there is a
length limit.  Your application's name will be trucated to 27 letters
before adding the suffix.  The "save" file is always placed in the target
application's folder.

5.  You guessed it! The place to put your resources is in the resource fork
of the datafile.  The dialog info is saved in the data fork.  ALL resources
found in the resource fork, if any, will be merged into your target
application, replacing any previous versions of the same Type and ID.
Optionally, you can make this file ahead of time, perhaps from Resource
Editor, and use it to store all your resources.  Bind.Icons program will
find and use the file, provided it has the proper ("--.bag") name and is
located in the same folder as the target application.

6.  WARNING: If you install a new signature and ICN#, then copy the file,
and then change one copy to a different ICN# with the SAME signature ..you
lose the game! Put the reserve copy on a different volume before re-running
Bind.Icons with a different ICN# (but the same signature).  Remember, your
hard disk is probably all one volume.  This is further explained in the
following:


Why It Works.

   Finder has this simple rule: he saves one and only one copy of each
different bundle he encounters.  What is a bundle? It's a statement linking
a particular signature with a particular ICN#.  What is a "different"
bundle? It's a bundle with a different signature.

   So Finder pokes along looking at files.  He sees an application with a
previously unknown signature.  Grumbling, he stores a copy of that bundle
in Desk Top, an invisible file in the root directory.  This COPY of the
bundle (stored in Desk Top) is what reminds Finder to display the
application with that signature using such-and-such icon.

   Pretty soon he finds another application with the same signature.  Now
Finder is not about to go to the trouble of checking whether this
application wants a different icon.  He already has a bundle with that
signature, and that's it! No more.  "You want a different icon, buddy? You
get yourself a different signature".

   So if you want Finder to use a different ICN# you have to change BOTH
signature and ICN# SIMULTANEOUSLY.  Doesn't work if you change the
signature and then return to the Finder before changing the ICN# resource
(for example with Resource Editor).  It doesn't matter how skillfully you
swap ICN# resources.  Once Finder has had a look at your application with
the new signature he will never think about it again.  He already "knows"
which icon to use...  the old one which was there during that brief passage
through the Finder on the way to Resource Editor.

   So suppose you destroy the Desk Top file.  This often works.  But not if
you have left a copy of your application with the new signature, but an old
ICN#, ANYWHERE on your application's volume.  (That may mean anywhere on
your hard disk, in any folder.) When Finder rebuilds the Desk Top he will
save the first bundle he finds with that signature, and that's all.
Probably it will be the other one, not the one you want.

   You can have as many copies of (old signature - old icon) as you want.
You can have as many copies of (new signature - new icon) as you want.
         *** NEVER LET THE FINDER SEE SOMETHING IN-BETWEEN ***


Technical Details:

   Bind.Icons does a bit of surgery on the Desk Top file, the one that is
located in the root directory of the volume which contains the target
application.  It simply removes all BNDL's (and associated FREF's) which
have the new signature, if any were present.  In effect it has wiped part
of Desk Top leaving the rest.  Next time around, Finder will not recognize
this signature.  He will save the application's bundle (signature-ICN#
combo) in the Desk Top and will use it to display the application on the
screen.  There had better be only one such (signature-ICN# combo) around
for him to find!